feat: Python SDK (Surface 2) + run-control API + adapters (step 8) - #6
Merged
Conversation
Deep control over a governed run from Python. The SDK is a thin, stdlib-only
client; the Go core makes every deterministic decision.
Go (run-control endpoints the SDK drives):
- POST /v1/runs (create with budget), POST /v1/runs/{id}/steps (loop/time
enforcement -> 402 on halt), POST /v1/runs/{id}/checkpoints,
POST /v1/runs/{id}/cancel, POST /v1/runs/{id}/approvals (request, non-blocking),
GET /v1/approvals/{id} (poll). approval.Gate.Create added for the poll model.
- api/v1 extended additively; tests for every endpoint incl. loop-budget 402,
checkpoint round-trip, approval request->poll->resolve.
Python (sdks/python, package `riskkernel`, zero runtime deps):
- client.RiskKernel (urllib); 402 -> BudgetExceeded.
- Runtime / governed_run / Budget / Run (step, checkpoint, cancel, proxy_config);
ApprovalGate + @governed_tool; current_run contextvar; env-configured default.
- Adapters (lazy-imported, no hard deps): LangChain CallbackHandler,
Claude Agent SDK PreToolUse hook, OpenAI Agents SDK RunHooks.
- pyproject (hatchling, Apache-2.0), README, unittest suite against a stdlib
stub daemon. Verified end-to-end against the real daemon.
- CI: Python SDK workflow on 3.9 / 3.12.
Model-call metering stays in the proxy: route the SDK's LLM calls through
run.proxy_config(), so the SDK never re-implements governance.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Implements Surface 2 — the Python SDK (§8 step 8): deep, in-process control over a governed run. The SDK is a thin, stdlib-only client; the Go core makes every deterministic decision (budgets, halts, approval policy).
Go — run-control endpoints (additive to
api/v1)POST /v1/runs(create with budget),POST /v1/runs/{id}/steps(loop/time enforcement → 402 on halt),POST /v1/runs/{id}/checkpoints,POST /v1/runs/{id}/cancel,POST /v1/runs/{id}/approvals(non-blocking request),GET /v1/approvals/{id}(poll).approval.Gate.Createfor the SDK poll model. Tests cover every endpoint (loop-budget 402, checkpoint round-trip, approval request→poll→resolve, auto-approve).Python —
pip install riskkernel(zero runtime deps)Runtime/governed_run/Budget;Run.step/checkpoint/cancel/proxy_config;ApprovalGate+@governed_tool;current_runcontextvar.run.proxy_config(), so the SDK never re-implements governance.CallbackHandler, Claude Agent SDK PreToolUse hook, OpenAI Agents SDKRunHooks.pyproject(hatchling), README,unittestsuite against a stdlib stub daemon.Verification
go test -race ./...green;vet+gofmtclean.BudgetExceeded→ checkpoint round-trip → approval request→resolve→approved → read-only auto-approve.